API Reference
Packages
formance.com/v1beta1
Package v1beta1 contains API Schema definitions for the formance v1beta1 API group.
It allow to configure a Formance stack.
A stack is composed of a Stack resource and some modules.
Each module can create multiple resources following its needs. See Other resources.
Various parts of the stack can be configured either using the CRD properties or using some Settings.
Modules :
Other resources :
- AuthClient
- Benthos
- BenthosStream
- Broker
- BrokerConsumer
- BrokerTopic
- Database
- GatewayHTTPAPI
- ResourceReference
- Versions
Main resources
Stack
Stack represents a formance stack. A Stack is basically a container. It holds some global properties and creates a namespace if not already existing.
To do more, you need to create some modules.
The Stack resource allow to specify the version of the stack.
It can be specified using either the field .spec.version or the .spec.versionsFromFile field (Refer to the documentation of Versions resource.
The version field will have priority over versionFromFile.
If versions and versionsFromFile are not specified, "latest" will be used.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Stack | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec StackSpec | |||
status StackStatus |
StackSpec
| Field | Description | Default | Validation |
|---|---|---|---|
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to specify the version of the components Must be a valid docker tag | ||
versionsFromFile string | VersionsFromFile allow to specify a formance.com/Versions object which contains individual versions for each component. Must reference a valid formance.com/Versions object | ||
enableAudit boolean | EnableAudit enable audit at the stack level. Actually, it enables audit on Gateway | false | |
disabled boolean | Disabled indicate the stack is disabled. A disabled stack disable everything It just keeps the namespace and the Database resources. | false |
StackStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
modules string array | Modules register detected modules |
Settings
Settings represents a configurable piece of the stacks.
The purpose of this resource is to be able to configure some common settings between a set of stacks.
Example :
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: postgres-uri
spec:
key: postgres.ledger.uri
stacks:
- stack0
value: postgresql://postgresql.formance.svc.cluster.local:5432
This example create a setting named postgres-uri targeting the stack named stack0 and the service ledger (see the key postgres.ledger.uri).
Therefore, a Database created for the stack stack0 and the service named 'ledger' will use the uri postgresql://postgresql.formance.svc.cluster.local:5432.
Settings allow to use wildcards in keys and in stacks list.
For example, if you want to use the same database server for all the modules of a specific stack, you can write :
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: postgres-uri
spec:
key: postgres.*.uri # There, we use a wildcard to indicate we want to use that setting of all services of the stack `stack0`
stacks:
- stack0
value: postgresql://postgresql.formance.svc.cluster.local:5432
Also, we could use that setting for all of our stacks using :
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: postgres-uri
spec:
key: postgres.*.uri # There, we use a wildcard to indicate we want to use that setting for all services of all stacks
stacks:
- * # There we select all the stacks
value: postgresql://postgresql.formance.svc.cluster.local:5432
Some settings are really global, while some are used by specific module.
Refer to the documentation of each module and resource to discover available Settings.
Global settings
AWS account
A stack can use an AWS account for authentication.
It can be used to connect to any AWS service we could use.
It includes RDS, OpenSearch and MSK. To do so, you can create the following setting:
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: aws-service-account
spec:
key: aws.service-account
stacks:
- '*'
value: aws-access
This setting instruct the operator than there is somewhere on the cluster a service account named aws-access.
So, each time a service has the capability to use AWS, the operator will use this service account.
The service account could look like that :
apiVersion: v1
kind: ServiceAccount
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::************:role/staging-eu-west-1-hosting-stack-access
labels:
formance.com/stack: any
name: aws-access
You can note two things :
- We have an annotation indicating the role arn used to connect to AWS. Refer to the AWS documentation to create this role
- We have a label
formance.com/stack=anyindicating we are targeting all stacks. Refer to the documentation of ResourceReference for further information.
JSON logging
You can use the setting logging.json with the value true to configure elligible service to log as json.
Example:
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: json-logging
spec:
key: logging.json
stacks:
- '*'
value: "true"
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Settings | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec SettingsSpec |
SettingsSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stacks string array | Stacks on which the setting is applied. Can contain * to indicate a wildcard. | ||
key string | The setting Key. See the documentation of each module or global settings to discover them. | ||
value string | The value. It must have a specific format following the Key. |
Modules
Auth
Auth represent the authentication module of a stack.
It is an OIDC compliant server.
Creating it for a stack automatically add authentication on all supported modules.
The auth service is basically a proxy to another OIDC compliant server.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Auth | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec AuthSpec | |||
status AuthStatus |
AuthSpec
| Field | Description | Default | Validation |
|---|---|---|---|
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
stack string | Stack indicates the stack on which the module is installed | ||
delegatedOIDCServer DelegatedOIDCServerConfiguration | Contains information about a delegated authentication server to use to delegate authentication | ||
signingKey string | Allow to override the default signing key used to sign JWT tokens. | ||
signingKeyFromSecret SecretKeySelector | Allow to override the default signing key used to sign JWT tokens using a k8s secret | ||
enableScopes boolean | Allow to enable scopes usage on authentication. If not enabled, each service will check the authentication but will not restrict access following scopes. in this case, if authenticated, it is ok. | false |
DelegatedOIDCServerConfiguration
| Field | Description | Default | Validation |
|---|---|---|---|
issuer string | Issuer is the url of the delegated oidc server | ||
clientID string | ClientID is the client id to use for authentication | ||
clientSecret string | ClientSecret is the client secret to use for authentication |
AuthStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
clients string array | Clients contains the list of clients created using AuthClient |
Gateway
Gateway is the Schema for the gateways API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Gateway | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec GatewaySpec | |||
status GatewayStatus |
GatewaySpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
ingress GatewayIngress | Allow to customize the generated ingress |
GatewayIngress
| Field | Description | Default | Validation |
|---|---|---|---|
host string | Indicates the hostname on which the stack will be served. Example : formance.example.com | ||
scheme string | Indicate the scheme. Actually, It should be https unless you know what you are doing. | https | |
annotations object (keys:string, values:string) | Custom annotations to add on the ingress | ||
tls GatewayIngressTLS | Allow to customize the tls part of the ingress |
GatewayIngressTLS
| Field | Description | Default | Validation |
|---|---|---|---|
secretName string | Specify the secret name used for the tls configuration on the ingress |
GatewayStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
syncHTTPAPIs string array | Detected http apis. See GatewayHTTPAPI | ||
authEnabled boolean | Indicates if a Auth module has been detected. | false |
Ledger
Ledger is the module allowing to install a ledger instance.
The ledger is actually a stateful application on the writer part. So we cannot scale the ledger as we want without prior configuration.
So, the ledger can run in two modes :
- single instance: Only one instance will be deployed. We cannot scale in that mode.
- single writer / multiple reader: In this mode, we will have a single writer and multiple readers if needed.
Use setting ledger.deployment-strategy with either the value :
- single : For the single instance mode.
- single-writer: For the single writer / multiple reader mode. Under the hood, the operator create two deployments and force the scaling of the writer to stay at 1. Then you can scale the deployment of the reader to the value you want.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Ledger | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec LedgerSpec | |||
status LedgerStatus |
LedgerSpec
| Field | Description | Default | Validation |
|---|---|---|---|
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
stack string | Stack indicates the stack on which the module is installed | ||
deploymentStrategy DeploymentStrategy | Deprecated. | single | |
locking LockingStrategy | Locking is intended for ledger v1 only |
DeploymentStrategy
Underlying type: string
LockingStrategy
| Field | Description | Default | Validation |
|---|---|---|---|
strategy string | memory | ||
redis LockingStrategyRedisConfig |
LockingStrategyRedisConfig
| Field | Description | Default | Validation |
|---|---|---|---|
uri string | |||
tls boolean | false | ||
insecure boolean | false | ||
duration string | |||
retry string |
LedgerStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Orchestration
Orchestration is the Schema for the orchestrations API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Orchestration | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec OrchestrationSpec | |||
status OrchestrationStatus |
OrchestrationSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module |
OrchestrationStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
temporalURI string | Type: string |
Payments
Payments is the Schema for the payments API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Payments | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec PaymentsSpec | |||
status PaymentsStatus |
PaymentsSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
encryptionKey string |
PaymentsStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Reconciliation
Reconciliation is the Schema for the reconciliations API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Reconciliation | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec ReconciliationSpec | |||
status ReconciliationStatus |
ReconciliationSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module |
ReconciliationStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Search
Search is the Schema for the searches API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Search | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec SearchSpec | |||
status SearchStatus |
SearchSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
batching Batching |
Batching
Batching allow to define custom batching configuration
| Field | Description | Default | Validation |
|---|---|---|---|
count integer | Count indicates the number of messages that can be kept in memory before being flushed to ElasticSearch | ||
period string | Period indicates the maximum duration messages can be kept in memory before being flushed to ElasticSearch |
SearchStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
elasticSearchURI string | Type: string | ||
topicCleaned boolean | TopicCleaned is used to flag stacks where the topics have been cleaned (still search-ledgerv2 and co consumers) | false |
Stargate
Stargate is the Schema for the stargates API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Stargate | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec StargateSpec | |||
status StargateStatus |
StargateSpec
| Field | Description | Default | Validation |
|---|---|---|---|
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
stack string | Stack indicates the stack on which the module is installed | ||
serverURL string | |||
organizationID string | |||
stackID string | |||
auth StargateAuthSpec |
StargateAuthSpec
| Field | Description | Default | Validation |
|---|---|---|---|
clientID string | |||
clientSecret string | |||
issuer string |
StargateStatus
StargateStatus defines the observed state of Stargate
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Wallets
Wallets is the Schema for the wallets API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Wallets | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec WalletsSpec | |||
status WalletsStatus |
WalletsSpec
| Field | Description | Default | Validation |
|---|---|---|---|
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module | ||
stack string | Stack indicates the stack on which the module is installed |
WalletsStatus
WalletsStatus defines the observed state of Wallets
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Webhooks
Webhooks is the Schema for the webhooks API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Webhooks | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec WebhooksSpec | |||
status WebhooksStatus |
WebhooksSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
version string | Version allow to override global version defined at stack level for a specific module |
WebhooksStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Other resources
AuthClient
AuthClient allow to create OAuth2/OIDC clients on the auth server (see Auth)
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | AuthClient | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec AuthClientSpec | |||
status AuthClientStatus |
AuthClientSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
id string | ID indicates the client id It must be used with oauth2 client_id parameter | ||
public boolean | Public indicate whether a client is confidential or not. Confidential clients are clients which the secret can be kept secret... As opposed to public clients which cannot have a secret (application single page for example) | false | |
description string | Description represents an optional description of the client | ||
redirectUris string array | RedirectUris allow to list allowed redirect uris for the client | ||
postLogoutRedirectUris string array | RedirectUris allow to list allowed post logout redirect uris for the client | ||
scopes string array | Scopes allow to five some scope to the client | ||
secret string | Secret allow to configure a secret for the client. It is not required as some client could use some oauth2 flows which does not requires a client secret |
AuthClientStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Benthos
Benthos is the Schema for the benthos API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Benthos | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BenthosSpec | |||
status BenthosStatus |
BenthosSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
debug boolean | Allow to enable debug mode on the module | false | |
dev boolean | Allow to enable dev mode on the module Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example) | false | |
resourceRequirements ResourceRequirements | |||
batching Batching | |||
initContainers Container array |
Batching
Batching allow to define custom batching configuration
| Field | Description | Default | Validation |
|---|---|---|---|
count integer | Count indicates the number of messages that can be kept in memory before being flushed to ElasticSearch | ||
period string | Period indicates the maximum duration messages can be kept in memory before being flushed to ElasticSearch |
BenthosStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
elasticSearchURI string | Type: string |
BenthosStream
BenthosStream is the Schema for the benthosstreams API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | BenthosStream | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BenthosStreamSpec | |||
status BenthosStreamStatus |
BenthosStreamSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
data string | |||
name string |
BenthosStreamStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Broker
Broker is the Schema for the brokers API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Broker | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BrokerSpec | |||
status BrokerStatus |
BrokerSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed |
BrokerStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
uri string | Type: string | ||
mode Mode | Mode indicating the configuration of the nats streams Two modes are defined : * OneStreamByService: In this case, each service will have a dedicated stream created * OneStreamByStack: In this case, a stream will be created for the stack and each service will use a specific subject inside this stream | Enum: [OneStreamByService OneStreamByStack] | |
streams string array | Streams list streams created when Mode == ModeOneStreamByService |
Mode
Underlying type: string
Mode defined how streams are created on the broker (mainly nats)
BrokerConsumer
BrokerConsumer is the Schema for the brokerconsumers API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | BrokerConsumer | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BrokerConsumerSpec | |||
status BrokerConsumerStatus |
BrokerConsumerSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
services string array | |||
queriedBy string | |||
name string | As the name is optional, if not provided, the name will be the QueriedBy property This is only applied when using one stream by stack see Mode |
BrokerConsumerStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
BrokerTopic
BrokerTopic is the Schema for the brokertopics API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | BrokerTopic | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BrokerTopicSpec | |||
status BrokerTopicStatus |
BrokerTopicSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
service string |
BrokerTopicStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors |
Database
Database represent a concrete database on a PostgreSQL server, it is created by modules requiring a database (Ledger for example).
It uses the settings postgres.<module-name>.uri which must have the following uri format: postgresql://[<username>@<password>]@<host>/<db-name>
Additionally, the uri can define a query param secret indicating a k8s secret, than must be used to retrieve database credentials.
On creation, the reconciler behind the Database object will create the database on the postgresql server using a k8s job.
On Deletion, by default, the reconciler will let the database untouched.
You can allow the reconciler to drop the database on the server by using the Settings clear-database with the value true.
If you use that setting, the reconciler will use another job to drop the database.
Be careful, no backup are performed!
Database resource honors aws.service-account setting, so, you can create databases on an AWS server if you need.
See AWS accounts
Once a database is fully configured, it retains the postgres uri used.
If the setting indicating the server uri changed, the Database object will set the field .status.outOfSync to true
and will not change anything.
Therefore, to switch to a new server, you must change the setting value, then drop the Database object. It will be recreated with correct uri.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Database | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec DatabaseSpec | |||
status DatabaseStatus |
DatabaseSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
service string | Service is a discriminator for the created database. Actually, it will be the module name (ledger, payments...). Therefore, the created database will be named <stack-name><service> | ||
debug boolean | false |
DatabaseStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
uri string | Type: string | ||
database string | The generated database name | ||
outOfSync boolean | OutOfSync indicates than a settings changed the uri of the postgres server The Database object need to be removed to be recreated |
GatewayHTTPAPI
GatewayHTTPAPI is the Schema for the HTTPAPIs API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | GatewayHTTPAPI | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec GatewayHTTPAPISpec | |||
status GatewayHTTPAPIStatus |
GatewayHTTPAPISpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
name string | Name indicates prefix api | ||
rules GatewayHTTPAPIRule array | Rules | ||
healthCheckEndpoint string | Health check endpoint |
GatewayHTTPAPIRule
| Field | Description | Default | Validation |
|---|---|---|---|
path string | |||
methods string array | |||
secured boolean | false |
GatewayHTTPAPIStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
ready boolean |
ResourceReference
ResourceReference is a special resources used to refer to externally created resources.
It includes k8s service accounts and secrets.
Why? Because the operator create a namespace by stack, so, a stack does not have access to secrets and service accounts created externally.
A ResourceReference is created by other resource who need to use a specific secret or service account.
For example, if you want to use a secret for your database connection (see Database, you will
create a setting indicating a secret name. You will need to create this secret yourself, and you will put this
secret inside the namespace you want (default maybe).
The Database reconciler will create a ResourceReference looking like that :
apiVersion: formance.com/v1beta1
kind: ResourceReference
metadata:
name: jqkuffjxcezj-qlii-auth-postgres
ownerReferences:
- apiVersion: formance.com/v1beta1
blockOwnerDeletion: true
controller: true
kind: Database
name: jqkuffjxcezj-qlii-auth
uid: 2cc4b788-3ffb-4e3d-8a30-07ed3941c8d2
spec:
gvk:
group: ""
kind: Secret
version: v1
name: postgres
stack: jqkuffjxcezj-qlii
status:
...
This reconciler behind this ResourceReference will search, in all namespaces, for a secret named "postgres".
The secret must have a label formance.com/stack with the value matching either a specific stack or any to target any stack.
Once the reconciler has found the secret, it will copy it inside the stack namespace, allowing the ResourceReconciler owner to use it.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | ResourceReference | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec ResourceReferenceSpec | |||
status ResourceReferenceStatus |
ResourceReferenceSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stack string | Stack indicates the stack on which the module is installed | ||
gvk GroupVersionKind | |||
name string |
ResourceReferenceStatus
| Field | Description | Default | Validation |
|---|---|---|---|
ready boolean | Ready indicates if the resource is seen as completely reconciled | ||
info string | Info can contain any additional like reconciliation errors | ||
syncedResource string | |||
hash string |
Versions
Versions is the Schema for the versions API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | formance.com/v1beta1 | ||
kind string | Versions | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec object (keys:string, values:string) |